// ==================================================================================
// Shared Genomics Project MPI Codebase
// Version 1.0 30/04/2010
//
// (c) 2010 University of Manchester all rights reserved
//
// This file is distributed under the GNU General Public License, Version 2.  
// Please see the file COPYING.txt for more details
// ==================================================================================

#ifndef _ASSOC_UTILS_H_
#define _ASSOC_UTILS_H_

#include "options.h"

#ifdef __cplusplus
extern "C" {
#endif

/*!
\file
\ingroup	gio
\brief		File Utility functions for 1-D Association Scans 
\details
	A series of utility functions used by the single association
	MPI programs to wrap common file I/O operations 
	and reduce the size of the program main body.
*/

#ifndef MAX_LINE_LENGTH
#define MAX_LINE_LENGTH 1024
#endif

/*!
\brief Write a permutation count file and copy to a remote directory 
\details
	The output filename is a concationation of \ref selected_options::rdir, \ref selected_options::szRunId,
	the processor rank and specified file suffix.<br>
\param [in] ops Output file location
\param [in] suffix Suffix for the output file
\param [in] rank Rank of the local processor
\param [in] numprocs No. processors associated with a MPI calculation
\param [in] nperm_done No. permutation run of a local rank
\param [in] size Size of the permutation data arrays
\param [in] R permutation data for empirical p-value calculation (cf. EMP1 of PLINK)
\param [in] maxR permutation data for Familywise Error Rate (FWER) calculation (cf. EMP2 of PLINK)
\returns 1 on success or 0 on failure
*/
int count_file_write_and_copy(struct selected_options *ops, char *suffix, int rank, int numprocs, int nperm_done, int size, int *R, int *maxR);

/*!
\brief Read a set of permutation count files
\details
	The input filename are concationations of \ref selected_options::rdir, \ref selected_options::szRunId,
	the expected processor ranks from numprocs and the specified file suffix.<br>
	Each input file is copied to a local directory (\ref selected_options::ldir) before parsing.
\param [in] ops Input file location
\param [in] suffix Suffix for the output file
\param [in] numprocs No. processors associated with the results of an MPI calculation
\param [in] size Size of the permutation data arrays
\param [in,out] nperm_done No. permutation run of a local rank
\param [in,out] R permutation data for empirical p-value calculation (cf. EMP1 of PLINK)
\param [in,out] maxR permutation data for Familywise Error Rate (FWER) calculation (cf. EMP2 of PLINK)
\param [in,out] hasCopiedAll Flag set if all expected input files read from remote directory
\param [in,out] file_copy_failures Flags set to ranks that failed to produce expected 'count' input data.
\returns 1 on success or 0 on failure
*/
int count_file_copy_and_parse(struct selected_options *ops, char *suffix, int numprocs, int size, int *nperm_done, int *R, int *maxR, BOOL *hasCopiedAll, BOOL *file_copy_failures);

/*! 
\brief Log list of failed MPI ranks.
\details
	Output filename a concatonation of \ref selected_options::rdir, 
	\ref selected_options::szRunId and SUFFIX_MERGE_LOG .
\param [in] ops Output file location
\param [in] numprocs No. processors associated with an MPI calculation
\param [in] failures Array of failed ranks (index == TRUE on failure)
\returns 1 on success or 0 on failure
*/
int write_failed_rank_log(struct selected_options *ops, int numprocs, BOOL *failures);

/*! 
\brief Delete superfluous output files.
\details
	Deletion of superfluous output files will only leave 
	any final CSV files and text log files in a remote working directory.<br>
	Input filenames a concatonation of \ref selected_options::rdir, 
	\ref selected_options::szRunId and the specified file suffix.<br>
	This function should only be called if a 'run' was successful.
\param [in] ops Input file location
\param [in] suffix Input file suffix
\param [in] numprocs No. processors associated with an MPI calculation
\returns 1 on success or 0 on failure
*/
int assoc_cleanup_temp_files(struct selected_options *ops, char *suffix, int numprocs);

/*!
\brief Write a text permutation count file and copy to a remote directory 
\details
	The output filename is a concationation of \ref selected_options::rdir, \ref selected_options::szRunId,
	the processor rank and specified file suffix.<br>
	The output file is text formatted.
	N/B
\param [in] ops Output file location
\param [in] suffix Suffix for the output file
\param [in] rank Rank of the local processor
\param [in] numprocs No. processors associated with a MPI calculation
\param [in] nperm_done No. permutation run of a local rank
\param [in] size Size of the permutation data arrays
\param [in] R permutation data for empirical p-value calculation (cf. EMP1 of PLINK)
\param [in] maxR permutation data for Familywise Error Rate (FWER) calculation (cf. EMP2 of PLINK)
\returns 1 on success or 0 on failure
*/
int count_file_write_and_copy(struct selected_options *ops, char *suffix, int rank, int numprocs, int nperm_done, int size, int *R, int *maxR);

/*!
\brief Write a binary permutation count file and copy to a remote directory 
\details
	The output filename is a concationation of \ref selected_options::rdir, \ref selected_options::szRunId,
	the processor rank and specified file suffix.<br>
	The output file is binary formatted.
	N/B
\param [in] ops Output file location
\param [in] suffix Suffix for the output file
\param [in] rank Rank of the local processor
\param [in] numprocs No. processors associated with a MPI calculation
\param [in] nperm_done No. permutation run of a local rank
\param [in] size Size of the permutation data arrays
\param [in] R permutation data for empirical p-value calculation (cf. EMP1 of PLINK)
\param [in] maxR permutation data for Familywise Error Rate (FWER) calculation (cf. EMP2 of PLINK)
\returns 1 on success or 0 on failure
*/
int _count_file_write_and_copy(struct selected_options *ops, char *suffix, int rank, int numprocs, int nperm_done, int size, int *R, int *maxR);

/*!
\brief Read a set of binary permutation count files
\details
	The input filename are concationations of \ref selected_options::rdir, \ref selected_options::szRunId,
	the expected processor ranks from numprocs and the specified file suffix.<br>
	Each input file is copied to a local directory (\ref selected_options::ldir) before parsing.
	This code parses binary permutation count files.
\param [in] ops Input file location
\param [in] suffix Suffix for the output file
\param [in] size Size of the permutation data arrays
\param [in,out] nperm_done No. permutation run of a local rank
\param [in,out] R permutation data for empirical p-value calculation (cf. EMP1 of PLINK)
\param [in,out] maxR permutation data for Familywise Error Rate (FWER) calculation (cf. EMP2 of PLINK)
\param [in,out] hasCopiedAll Flag set if all expected input files read from remote directory
\param [in,out] numprocs No. processors associated with the results of an MPI calculation
\returns 1 on success or 0 on failure
*/
BOOL* _count_file_parse(struct selected_options *ops, char *suffix, int size, int *nperm_done, int *R, int *maxR, BOOL *hasCopiedAll, int *numprocs);

#ifdef __cplusplus
}
#endif

#endif // _ASSOC_UTILS_H_